IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/u_man/cat1/pixie.z/pixie

Text File | 2002-10-03 | 17.9 KB | 397 lines

PPPPIIIIXXXXIIIIEEEE((((1111))))                                                              PPPPIIIIXXXXIIIIEEEE((((1111))))



NNNNAAAAMMMMEEEE
     pixie - add profiling code to an executable file

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ppppiiiixxxxiiiieeee file [ options ]

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _p_i_x_i_e is an object instrumentation tool that can be used to measure code
     execution frequency in a program for performance analysis.  _p_i_x_i_e reads
     an executable program, partitions it into basic blocks, and writes an
     equivalent program containing additional code that counts the execution
     of each basic block. (A basic block is a region of the program that can
     be entered only at the beginning and exited only at the end).

     Other options allow producing an uninstrumented copy of the executable,
     with map and graph sections added, and producing an instrumented
     executable for just counting function calls (arcs).

     _p_i_x_i_e is normally invoked from the SpeedShop _s_s_r_u_n(1) command; when it is
     so invoked, the SpeedShop runtime will be inserted into the program, and,
     when the program is run, it will generate a SpeedShop experiment file
     with the appropriate count data.  Data will be generated if the process
     exits normally, or received a fatal signal, unless the user has installed
     his or her own handler for that signal.  If the process invokes any of
     the various _d_l_o_p_e_n() calls, the DSO requested will be automatically
     instrumented, and the instrumented version added to the process.

     _p_r_o_f(1) can analyze these files and produce a listing of profiling data.
     See its man pages for more details.

     _e_l_f_d_u_m_p(1) can be used to dump out the contents of the various sections
     added to an executable by _p_i_x_i_e.

     _p_i_x_i_e(1) adds its runtime _D_S_O(5) to the liblist of the executable.  The
     normal rules _r_l_d(1) uses for LD_LIBRARY_PATH, _RLD_ROOT, and their abi
     variants apply to locating the _p_i_x_i_e runtime dso _l_i_b_p_i_x_r_t._s_o.

DDDDIIIIRRRREEEECCCCTTTT IIIINNNNVVVVOOOOCCCCAAAATTTTIIIIOOOONNNN OOOOFFFF PPPPIIIIXXXXIIIIEEEE
     _p_i_x_i_e may also be directly invoked by a user, in which case the SpeedShop
     runtime is not inserted. When the instrumented program is run, it will
     generate a file containing the basic block counts.  The pixified
     executable will creat a counts file in the event of fatal signals as long
     as the executable does not override the signal handlers set up by the
     _p_i_x_i_e(1) runtime.

     The name of the output .Counts file is that of the original program with
     any leading directory names removed and ".Counts" appended.  If the
     program during runtime executes calls to _s_p_r_o_c(_2) , _s_p_r_o_c_s_p_c(_2) or
     _f_o_r_k(_2) then multiple ".Counts" files will be generated, one for each
     process in the share group.  In this case, each ".Counts" file will
     additionally have the process id appended to the name.  If the process
     invokes any of the various _d_l_o_p_e_n() calls, the DSO requested will NOT be



                                                                        PPPPaaaaggggeeee 1111






PPPPIIIIXXXXIIIIEEEE((((1111))))                                                              PPPPIIIIXXXXIIIIEEEE((((1111))))



     automatically instrumented; it is the user's responsibility to pre-
     instrument all such DSOs.  When instrumenting DSO's it is necessary to
     use one of the following switches: ----ddddssssoooo, ----ddddssssoooo33332222, ----ddddssssoooo66664444, depending on
     whether the DSO is o32, n32, or n64 respectively.

     _p_r_o_f(1) can analyze these .Counts files and produce a listing of
     profiling data.  If the ".Counts" file has a process id number appended
     to it, you will need to give prof the full name including the suffix. See
     the prof man pages for more details.

OOOOPPPPTTTTIIIIOOOONNNNSSSS
     _p_i_x_i_e is normally invoked by the _s_s_r_u_n(1) command, and not directly
     invoked by a user.  It recognizes the following arguments:

     ----ccccooooppppyyyy
          Produce a copy of the target with function list (map) and arc list
          (graph) sections, but no instrumentation.

     ----ffffccccnnnnccccoooouuuunnnnttttssss
          Produce an instrumented executable that counts function calls and
          arc calls, but not basic-block- or branch-counts.

     ----aaaaddddddddlllliiiibbbbssss _l_i_b_1._s_o:_l_i_b_2._s_o:..._l_i_b_N._s_o
          Specify one or more DSOs that should be add to the library list of
          the executable (if they are not already explicitly there).
          Default: no libraries are added.

     ----ppppiiiixxxxiiiieeee____ffffiiiilllleeee <_n_a_m_e>
          Specify the name of the pixiefied executable.
          Default: append ".pixie" (or an explicit suffix, as set by ----ssssuuuuffffffffiiiixxxx)
          to the original name.

     ----ccccoooouuuunnnnttttssss____ffffiiiilllleeee <_n_a_m_e>
          Specify the name to be used for the output .Counts file.
          Default: append ".Counts" to the original program name.

     ----ssssuuuuffffffffiiiixxxx <._s_u_f_f_i_x>
          Specify the suffix to be appended to the pixified executable and
          DSO.
          Default: For an a.out, append ".pixie" (although _s_s_r_u_n(1) always
          explicitly sets the suffix).  For DSOs, the default suffix depends
          on the build architecture of the DSO; for o32 it is ".pix32", for
          n32, it is ".pixn32", and for n64 it is ".pix64".

     ----ddddssssoooo
          Treat executable as a o32 DSO.
          Performs a search of standard o32 library directories (and
          LD_LIBRARY_PATH), and causes a "._p_i_x_3_2" extension to be used.

     ----ddddssssoooo33332222
          Treat executable as a n32 DSO.
          Performs a search of standard n32 library directories (and



                                                                        PPPPaaaaggggeeee 2222






PPPPIIIIXXXXIIIIEEEE((((1111))))                                                              PPPPIIIIXXXXIIIIEEEE((((1111))))



          LD_LIBRARYN32_PATH), and causes a "._p_i_x_n_3_2" extension to be used.

     ----ddddssssoooo66664444
          Treat executable as a n64 DSO.
          Performs a search of standard n64 library directories (and
          LD_LIBRARY64_PATH), and causes a "._p_i_x_6_4" extension to be used.

     ----ddddiiiirrrreeeeccccttttoooorrrryyyy _d_i_r_e_c_t_o_r_y__n_a_m_e
          Specify a directory for writing the output file(s).
          Default:  Current directory, "./".

     ----[[[[nnnnoooo]]]]aaaauuuuttttooooppppiiiixxxxiiiieeee
          [Prevents] or permits a recursive instrumenting with pixie of all
          dynamic shared libraries used by the input file during runtime.
          _p_i_x_i_e keeps the timestamp and checksum from the original executable.
          Before automatically instrumenting a shared library _p_i_x_i_e will check
          any <lib>.pixie that it finds matching the <lib> it is to instrument
          and sees if the fields match. If so they will not be re-
          instrumented.  This option is not useful if the input file is non-
          shared.  All DSO's used by the executable must to be instrumented in
          order for it to work correctly.
          Default:  ----aaaauuuuttttooooppppiiiixxxxiiiieeee for an executable; ----nnnnooooaaaauuuuttttooooppppiiiixxxxiiiieeee for a DSO.

     ----[[[[nnnnoooo]]]]vvvveeeerrrrbbbboooosssseeee
          [Prevents] or permits messages summarizing the binary-to-binary
          translation process.
          Default:  ----nnnnoooovvvveeeerrrrbbbboooosssseeee

     ----[[[[nnnnoooo]]]]lllloooonnnnggggbbbbrrrraaaannnncccchhhh
          When _p_i_x_i_e instruments the user program, some transformations can
          push a branch offset beyond its legal range and _p_i_x_i_e will generate
          warnings about branch offsets being out of range.  The -longbranch
          option will cause _p_i_x_i_e to transform these instructions into jumps.
          Default:  ----nnnnoooolllloooonnnnggggbbbbrrrraaaannnncccchhhh

     ----[[[[nnnnoooo]]]]ppppiiiiddddssss
          This option tells _p_i_x_i_e to append the process id number on the end
          of the ``.Counts'' name. This is useful if you want to run the
          program instrumented with _p_i_x_i_e through a variety of tests before
          generating the statistics with _p_r_o_f.  This option is only needed for
          the main program. It will be transferred automatically to the
          instrumented DSO's during runtime.  The -nopids options will always
          be overridden by a process that issues a _f_o_r_k(2) or _s_p_r_o_c(2) system
          call.
          Default:  ----nnnnooooppppiiiiddddssss

     The following options are currently supported for compatibility reasons,
     but are considered obsolescent, and will eventually be removed.  If you
     feel they are necessary for your work, please contact us.






                                                                        PPPPaaaaggggeeee 3333






PPPPIIIIXXXXIIIIEEEE((((1111))))                                                              PPPPIIIIXXXXIIIIEEEE((((1111))))



     ----[[[[nnnnoooo]]]]lllliiiibbbblllliiiisssstttt
          [Prevents] or permits printing the names and paths of dynamic shared
          libraries used by the input file during runtime. This uses the same
          default search path strategy used by _r_l_d and _p_r_o_f.  This list is
          useful for building a dependency list for makefiles and shell
          scripts. The name of the file is that of the original program with
          any leading directory names removed and ".liblist" appended.  While
          pixie can not detect and pre-instrument any DSOs that the program
          dynamically opens, the SpeedShop runtime does detect them, and will
          cause them to be instrumented before proceeding with the _d_l_o_p_e_n.
          Default:  ----nnnnoooolllliiiibbbblllliiiisssstttt

     ----[[[[nnnnoooo]]]]lllliiiibbbblllliiiissssttttoooonnnnllllyyyy
          [Prevents] or permits printing the names and paths of dynamic shared
          libraries used by the input file during runtime. This is the same as
          -_l_i_b_l_i_s_t except that in this case no other operations are performed.
          Default:  ----nnnnoooolllliiiibbbblllliiiissssttttoooonnnnllllyyyy

     ----[[[[nnnnoooo]]]]bbbbrrrraaaannnncccchhhhccccoooouuuunnnnttttssss
          [Prevents] or permits insertion of extra counters to track whether
          each branch instruction is taken or not taken.  When this option is
          used, _p_r_o_f understands the new information automatically and prints
          more statistics.
          The information produced:
                  branch to branch taken
                  branch to branch untaken
                  untaken conditional branches
                  taken conditional branches
                  taken conditional branches with bnop
                  untaken conditional branches with bnop
                  direction-predicted conditional branches with bnop
                  non-sequential fetches
                  taken branches per conditional branch
                  forward taken branches per conditional branch
                  forward untaken branches per conditional branch
                  backward taken branches per conditional branch
                  backward untaken branches per conditional branch
          Default: ----bbbbrrrraaaannnncccchhhhccccoooouuuunnnnttttssss.

     ----[[[[nnnnoooo]]]]ttttaaaabbbblllleeee
          [Disable] or enable dumping an ascii map of translations made by
          _p_i_x_i_e into the file <myprog>.table where <myprog> is the name of the
          original object.
          Default:  ----nnnnoooottttaaaabbbblllleeee

     ----[[[[nnnnoooo]]]]ccccaaaallllllll____ccccoooouuuunnnnttttssss
          [Disable] or enable collecting function invocation counts. This is
          used in conjunction with _p_r_o_f -_g_p_r_o_f.
          Default:  ----ccccaaaallllllll____ccccoooouuuunnnnttttssss






                                                                        PPPPaaaaggggeeee 4444






PPPPIIIIXXXXIIIIEEEE((((1111))))                                                              PPPPIIIIXXXXIIIIEEEE((((1111))))



     ----tttthhhhrrrreeeeeeeewwwwaaaayyyy _h_e_x _n_u_m_b_e_r
          Tell _p_i_x_i_e not to transform code around threeway transfers.  Such
          code lies in libgl.so and exists only on machines which have VGX,GTX
          and Reality Engine graphics boards. The number for the Reality
          Engine is 0x3000 and the number for VGX and GTX is 0x6000.
          Most applications are not affected by this, so it is recommended
          this option not be used unless the graphics are obviously behaving
          differently from the non-instrumented version.  The erroneous
          behavior most common is for the graphics to be completely black.
          Since _p_i_x_i_e currently uses a heuristic to find the threeway patterns
          it can be fooled into thinking it has found a threeway transfer when
          in fact it has not. Because of this, _p_i_x_i_e does not pass the
          -_t_h_r_e_e_w_a_y flag automatically to the shared object and the user must
          run _p_i_x_i_e separately on libgl.so when using -_t_h_r_e_e_w_a_y.
          Default: nnnnoooo tttthhhhrrrreeeeeeeewwwwaaaayyyy ssssuuuuppppppppoooorrrrtttt

     ----mmmmiiiippppssss1111
          Use the MIPS1 instruction set (R2000, R3000) for output executable.
          This option is only useful for translating a mips2 executable into a
          mips1 executable. If the executable is mips3 or greater it will have
          no affect.
          Default: the architecture of the input executable will be
          maintained.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     prof(1), ssrun(1), speedshop(1)

NNNNOOOOTTTTEEEESSSS
     Some programs, e.g., _u_n_c_o_m_p_r_e_s_s and _v_i, will treat their arguments
     differently when the name of the program is different.  If you are
     running the program manually, you may need to rename _m_y_p_r_o_g._p_i_x_i_e to
     _m_y_p_r_o_g for example.  If you are running the program with _s_s_r_u_n, the
     program will think it was invoked with the original name.

     When _p_i_x_i_e reports the size of the old and new code, the numbers are
     accurate in that the new code size reported is the size of the code _p_i_x_i_e
     will actually execute.  However, the new code size does not count read-
     only data (including a copy of the original text and another data block
     the same size as the original text) put into the text section.

     _s_i_z_e(1) on the _p_i_x_i_e output reports a much larger text size than _p_i_x_i_e,
     since _s_i_z_e counts everything in the text segment as text.

     Code instrumented by _p_i_x_i_e is substantially larger than the original
     code. Conditional branches that used to fit in the 16-bit branch
     displacement field are specially handled and normally do not generate a
     _p_i_x_i_e error.  In certain cases in which they cannot be handled, a warning
     may be generated.

     _p_i_x_i_e(1) currently cannot handle stripped programs.  _p_i_x_i_e will give a
     fatal error if it is invoked on a stripped executable.




                                                                        PPPPaaaaggggeeee 5555






PPPPIIIIXXXXIIIIEEEE((((1111))))                                                              PPPPIIIIXXXXIIIIEEEE((((1111))))



     _p_i_x_i_e(1) sets the PIXIE_INIT bit of the processor-specific flags in the
     ELF .dynamic section.  This guarantees the pixie-inserted initialization
     code of a dynamic shared libraries is executed before any other init
     code.  See _l_d(1).



















































                                                                        PPPPaaaaggggeeee 6666